home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 26.zip / BS1 part 26 / Powervisor v1.10b disk1.adf / ReadThisFirst < prev    next >
Text File  |  1991-11-29  |  52KB  |  1,070 lines
  1.  
  2.  
  3.         ###     ##   #     # #### ###   #     # ###   ##    ##   ###
  4.         #  #   #  #  #     # #    #  #  #     #  #   #  #  #  #  #  #
  5.         #   # #    # #     # #    #   # #     #  #  #     #    # #   #
  6.         #   # #    # #     # #    #   # #     #  #  #     #    # #   #
  7.         #   # #/¯¯¯#¯#¯¯¯¯¯#¯#¯¯¯¯#¯¯¯#¯#¯¯¯¯¯#¯¯#¯¯#¯¯¯¯¯#¯¯¯\# #   #
  8.         #  #  #    # #     # #    #  #  #     #  #   #    #    # #  #
  9.         ###  /#    # #     # ###  ###   #     #  #    #   #    #\###
  10.         #   / #    # #     # #    #  #  #     #  #     #  #    # #  #
  11.         #  /  #    #  #   #  #    #   #  #   #   #      # #    # #\  #
  12.         # /   #    #  # # #  #    #   #  #   #   #      # #    # # \ #
  13.         #/    #    #  # # #  #    #   #  #   #   #      # #    # #  \#
  14.         #      #  #   ## ##  #    #   #   # #    #  #  #   #  #  #   #
  15.        /#       ##    #   #  #### #   #    #    ###  ##     ##   #   #\
  16.       /                                                                \
  17.      /                                                                  \
  18.     /                                                                    \
  19.    /                                                                      \
  20.   /                                                                        \
  21.  /                                                                          \
  22. |¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|
  23. | Introduction and general information              Mon Sep 30 08:48:59 1991 |
  24. |____________________________________________________________________________|
  25.  
  26.  
  27.  
  28.  
  29.  
  30. PowerVisor V1.10ß    © Jorrit Tyberghein (sep 91)
  31. -----------------
  32.  
  33.    PowerVisor is a powerful debugger designed to do almost everything
  34.    you can think of. Even if you can't think of it it will probably still be
  35.    possible :-)
  36.  
  37.    What I meant to say with the above is that PowerVisor is
  38.    rather complex to use. I recommend that you read the tutorial sections
  39.    even if you think you can cope. Once you have mastered the program
  40.    you will probably be able to debug your programs in a very short
  41.    time.
  42.  
  43.    Note that I TRY to make PowerVisor as user friendly as possible (look
  44.    at the emphasis on the word 'try'). In this new version for example,
  45.    menus have been added (at least for the AmigaDOS 2.0 version) and some
  46.    of the errormessages are better.
  47.  
  48.    Read the tutor files and execute each command as mentioned
  49.    there. All lines you have to type are preceded by a '<'. Some special
  50.    keys are notated as <key>. <enter> is used for the return key.
  51.    All output from PowerVisor is preceded by a '>'.
  52.    If you must press two keys together there is a '+' between them:
  53.    <alt>+<enter>.
  54.  
  55.    All input and output in this tutorial is for the AmigaDOS 2.0
  56.    version. In most cases this does not matter. If there are
  57.    differences between the two versions it is mentioned in the tutorial
  58.    in the following form: (1.3 : .......)
  59.  
  60.  
  61. Shareware and disclaimer
  62. ------------------------
  63.  
  64.    PowerVisor is shareware. This means that you can copy it and give
  65.    to everybody. If you like the program and/or use it, I'd appreciate
  66.    it if you send me a contribution. If you send $25 US or more
  67.    you automatically get the next major release when one is available
  68.    (I will also add you to the list of registered users).
  69.    PLEASE send money by international money order, EuroCheck (in Belgian
  70.    Francs (BF) !) or cash, because it's very difficult for me to cash
  71.    in other checks !
  72.    If you want an update please state your current version.
  73.  
  74.    Note that PowerVisor may only be redestributed with ALL FILES
  75.    PRESENT (especially this file). Below follows a list of all files
  76.    in the PowerVisor distribution.
  77.  
  78.    NOTHING in the PowerVisor distribution may be redistributed seperatelly
  79.    or used in any commercial product without prior permission from
  80.    the author.
  81.  
  82.    Note that the quickhelp utilities ('MakeHelp', 'ArcFiles', 'Help',
  83.    'MakeHelp13', 'ArcFiles13' and 'Help13') are considered seperate
  84.    from PowerVisor. You may redistribute the quickhelp utilities
  85.    without the rest of PowerVisor if you really want to (read the
  86.    'Help.doc' and 'Help13.doc' files for possible restrictions).
  87.  
  88.    This is in fact a BETA VERSION. This means that there are still
  89.    some bugs to be solved. If you use this program you are
  90.    betatesting PowerVisor. Don't worry too much about this. I think
  91.    PowerVisor is rather stable. I use it a lot and I have not
  92.    yet crashed with the current version.
  93.  
  94.    I (THE AUTHOR) TAKE NO RESPONSIBILITY FOR DAMAGES INFLICTED BY
  95.    POWERVISOR AND THE OTHER PROGRAMS IN THIS DISTRIBUTION. YOU ARE
  96.    COMPLETELY RESPONSIBLE FOR ALL EFFECTS OF USING POWERVISOR
  97.    AND ANY OF THE OTHER PROGRAMS. USE AT YOUR OWN RISK !
  98.  
  99.  
  100. I'm sorry
  101. ---------
  102.  
  103.    I'm sorry for the bad English. I speak Dutch and English is
  104.    only my second language. The tutorial files as they are in
  105.    the current distribution are NOT corrected at all. I didn't
  106.    even reread everything. I'd very much appreciate corrections of the
  107.    online help and the tutorial files.
  108.  
  109.  
  110. Compatibility with PowerVisor V1.00ß and V1.01ß
  111. -----------------------------------------------
  112.  
  113.    PowerVisor is still in beta release. This means that big changes
  114.    are unavoidable. Here follow all things that have changed.
  115.    If you have made ARexx programs, scripts or ML-scripts you will
  116.    probably have to change some things :
  117.  
  118.       - 'refresh' ALWAYS expects two arguments. The second
  119.         argument (command) is no longer optional
  120.       - New 'pvcall 17' and other pvcall commands
  121.       - New strong quote operator (·)
  122.       - The '#' operator is removed. Replace it with the '\' operator :
  123.                #<var>     ---->     \(<var>,%s)
  124.       - The 'eval' function expects a string pointer instead of a string
  125.       - The 'libfunc' command expects a negative argument instead of
  126.         a positive one
  127.       - The <maximum number of functions> argument is removed from
  128.         the 'loadfd' command
  129.       - 'memory', 'view' and 'unasm' work differently when another
  130.         number of bytes is used (see documentation)
  131.       - All error numbers have changed because the obsolete error
  132.         numbers are removed
  133.       - The 'PVSD' fileformat ('loadtags', 'savetags') has changed.
  134.         There is no way to convert. You need the original source
  135.         (.struct file)
  136.       - 'why' command is gone and is replaced with an alias in
  137.         the standard PowerVisor-startup file
  138.       - Many fields described in 'TheWizardCorner' have changed. Some
  139.         pvcall functions have become obsolete and DO NOT work anymore.
  140.         Some pvcall functions have been REPLACED with others
  141.       - The PowerVisor expression evaluator is more strict. You MUST
  142.         close ALL brackets (also {} brackets)
  143.       - PowerVisor commands called from ARexx are not interruptable anymore
  144.         with <esc>
  145.       - Important change in the logical window system. (See the changes
  146.         section for more details)
  147.       - Major change in the history buffer mechanics. The history
  148.         buffer list has changed (see 'TheWizardCorner')
  149.       - The File format of s:PowerVisor-config has changed !
  150.         Please delete this file first before you start the new version of
  151.         PowerVisor !!!
  152.       - Commandline options for PowerVisor are removed since they were
  153.         not very useful
  154.       - 'scan' works differently. You don't need to free the string
  155.         allocated with 'scan'. The pointer to the input string is
  156.         NOT returned in 'rc' but in the predefined constant 'INPUT'
  157.       - The number of pens in the pentable has changed from 16 to 24
  158.  
  159.  
  160. The development cycle
  161. ---------------------
  162.  
  163.    I started development of PowerVisor (two and a half years
  164.    ago, February 1989) on an Amiga 500 with two diskdrives and one
  165.    megabyte of memory. (except for holidays, I only programmed in the
  166.    weekends since I was at my university for the rest of the week)
  167.    PowerVisor (at that time called 'PowerBase') was going to be a
  168.    structure viewer. The 'list' and 'info' commands are in fact the
  169.    most ancient commands in PowerVisor.
  170.    At that time I did not think about writing a debugger. I could
  171.    not even write one if I wanted to. After all, PowerVisor was
  172.    only my second machinelanguage program on Amiga and I was still
  173.    learning machinelanguage.
  174.    (my first program in machinelanguage was a little program to
  175.    blink the powerled, I made this program together with someone
  176.    else :-)
  177.    (In fact PowerVisor is also my last machinelanguage program, I
  178.    normally program in C)
  179.  
  180.    I bought my first harddrive about five months later (30 megs).
  181.  
  182.    Exactly one year ago (in September 1990) I bought my
  183.    Amiga 3000/16/40! Needless to say this was a great development
  184.    boost. I almost immediatelly expanded my Amiga to 4 megabytes
  185.    of memory.
  186.  
  187.    About one month ago I bought a second harddrive (52 megs) for
  188.    my Amiga 3000.
  189.  
  190.    At this moment (September 1991) the PowerVisor source is
  191.    approximatelly 32500 lines long and all other ascii files
  192.    (help files, scripts, ...) are approximatelly 33000 lines.
  193.  
  194.    Conclusion : If I were to start all over again, I would not use
  195.    machinelanguage (or perhaps only for the exception handling and
  196.    other special code). It is too much work. At this moment I don't
  197.    regret my choice of machinelanguage, but this is only because I
  198.    already have programmed all support routines and making some new
  199.    PowerVisor command or other feature is simply a matter of calling
  200.    the right routines.
  201.  
  202.  
  203. Bugs
  204. ----
  205.  
  206.    PowerVisor was programmed on an Amiga 3000 with AmigaDOS 2.0.
  207.    I have tested the program on AmigaDOS 1.3 and everything seemed
  208.    to work. I have not been able to test PowerVisor on any other
  209.    Amiga configuration.
  210.  
  211.    PowerVisor is a big program. This means that bugs are unavoidable.
  212.    If you find some bugs, or have some suggestions please write.
  213.    I'd like PowerVisor to be as bug free as possible.
  214.    In this distribution there is a file 'pv.bugs' describing all bugs
  215.    in the current version. Consult this file if you discover some
  216.    weird behaviour.
  217.  
  218.    Give (at least) the following information when you report a bug :
  219.  
  220.       - Hardware configurations you have used (if a bug occurs
  221.         on one hardware configuration but not on another one, please
  222.         give both hardware configurations)
  223.         Hardware configurations includes :
  224.                Processor (68000, 68010, 68020, 68030, 68040, ...)
  225.                Coprocessor (68881, 68882, ...)
  226.                MMU (68851, ...)
  227.                Amiga model (500, 1000, 2000, 2500/20, 2500/30, 3000/16,
  228.                   3000/25, 3000UX, 3000T, CDTV, ...)
  229.                Available memory (chip ram, fast ram, other, ...)
  230.                Harddisk information
  231.                Other hardware expansions (graphics card, sound card, ...)
  232.       - Software configuration you used
  233.         Software configuration includes :
  234.                Operating system (AmigaDOS 1.2, 1.3, 2.0)
  235.                   If you can run more than one operating system on
  236.                   your Amiga, test the bug in the different versions
  237.                Version of KickStart and WorkBench (in Workbench
  238.                   about menu or with 'version' cli command)
  239.                Other programs running while the bug occurs (screen
  240.                   blankers, popup programs, ...)
  241.       - Describe the bug and the sequence of commands needed to
  242.         get the bug
  243.         Describe all output (including flashing lights, strange sounds,
  244.         noises, ...)
  245.  
  246. History
  247. -------
  248.  
  249.    V1.00 :
  250.       - first release (on tapserv and ab20.larc.nasa.gov)
  251.    V1.01 :
  252.       - Bug fix : when 'mode fancy', 'mode nofancy', 'mode lace'
  253.         or 'mode nolace' failed (for example, because there is
  254.         a visitor window open on the PowerVisor screen) we didn't
  255.         restore the current mode. This means that when you
  256.         tried again later (after closing the visitor window) PowerVisor
  257.         would ignore the command
  258.       - Bug fix : when the 'mode' command failes because there is
  259.         not enough memory, we first try again with the old mode
  260.         settings before quitting PowerVisor
  261.       - New feature : new 'stack' command and 'getstack' function to
  262.         monitor stack usage for a specific task. 'stack' uses the
  263.         timer.device for very fast respons
  264.       - We removed an obsolete feature from 'refresh'. The optional
  265.         command argument is no longer optional
  266.       - The standard logical window commands have an extra optional
  267.         argument. With this you can specify the number of lines for a
  268.         logical window
  269.       - The previous new feature is also included in the 'openlw' command
  270.       - Bug fix :Logical windows are much more stable with big fonts and
  271.         small visible sizes. No more crashes when the logical window is
  272.         too small
  273.       - Bug fix : parsing of [<x>] operator in alias strings was not
  274.         completely correct. Because we did not ignore the operator
  275.         if <x> was no digit we could not quote the operator. This is
  276.         solved
  277.       - New PowerVisor debug mode accessible with 'pvcall 17'. This
  278.         debug mode is useful if you want to debug aliases, scripts,
  279.         key attachements or other special things in PowerVisor. Every
  280.         command is printed on the screen before it is executed
  281.       - Bug fix : 'if' function now always correctly parses the
  282.         arguments. Because of some very obscure bug it could happen
  283.         that the 'if' function parsed to much characters from the
  284.         string
  285.       - Added strong quote operator in strings because I needed it
  286.         in the 'salias' alias
  287.       - The '#' operator is removed because the same functionality
  288.         is already present in the quote operator '\'. Just use
  289.         \(<x>,%s) instead of #<x>
  290.       - Behaviour of the 'eval' function has changed ! 'eval' now
  291.         expects a string pointer (or normal pointer) instead of
  292.         a string. This turned out to be more useful
  293.       - Limitation removed in 'colrow' and 'fit' commands. It is
  294.         now possible to size the 'debug' logical window
  295.       - Bug fix : The 'colrow' and 'fit' commands are now very stable.
  296.         When an out of memory error occurs, they simply try again for
  297.         the old values. If this also fails PowerVisor will quit
  298.         (in the previous version a command like 'colrow 30000 30000'
  299.         would crash your amiga)
  300.       - Behaviour changed for 'libfunc' command : the offset argument
  301.         must be negative and only the 16 least significant bits
  302.         are used. Thus something like $ff30 is a valid offset (this
  303.         is also the format given by the disassembler)
  304.       - Bug fix : The 'loadfd' command now handles multiple ##bias
  305.         statements in fd-files correctly. In V1.00 all functions
  306.         where correctly loaded but not correctly counted. The effect
  307.         of this was that 'info <fd node>' did not show all functions
  308.         in the fd-file
  309.       - Removed a completely useles feature from 'loadfd' : it is
  310.         no longer possible to specify the maximum number of functions
  311.         to load. 'loadfd' always loads the complete fd-file
  312.       - Added workbench startup
  313.       - Startup is cleaner. We don't crash anymore if the wrong
  314.         PowerVisor is used on the wrong operating system.
  315.         We are also a lot more stable in low memory conditions and
  316.         other wierd environments
  317.       - We didn't close dos.library
  318.       - New 'Aliases' reference file explaining all aliases defined
  319.         in s/PowerVisor-startup and s/pv/ExtraAliases
  320.       - New aliases in s/PowerVisor-startup (salias and fdebug)
  321.       - The 'db' script is better. Opens a fixed size logical window
  322.         so you don't need to size it everytime you use the fullscreen
  323.         debugger. 'db' also redefines 'fdebug' to clean up the
  324.         fullscreen debugger
  325.       - New 'ExtraAliases' script to define some extra aliases
  326.       - Created flexible install script
  327.    V1.10 :
  328.       - Bug fix : PowerVisor no longer crashes when a logical window
  329.         is made too small
  330.       - Removed incorrect statement in 'CommandReference' about 'fit'
  331.         and 'colrow' not suitable for the 'debug' logical window
  332.       - Incorrect statement in 'Screen' removed. The 'debug' logical
  333.         window is 90 columns instead of 82
  334.       - New function 'lastbytes'. This function returns the last number
  335.         of bytes used with the 'memory' or 'view' command
  336.       - New function 'lastlines'. This function returns the last number
  337.         of lines used with the 'unasm' command
  338.       - 'memory', 'view' and 'unasm' remember the number of bytes or lines
  339.         viewed (see the previous functions) and will continue with this
  340.         number at a later time
  341.       - New aliases 'cm', 'cv' and 'cu' to continue 'memory', 'view'
  342.         and 'unasm' respectivelly without setting a new address. You
  343.         can set the number of bytes or lines though
  344.       - Bug fix : we don't allow illegal variable names any more
  345.       - Finally all obsolete errors are removed
  346.       - Bug fix : 'LoadTags' and 'SaveTags' correctly handle structures.
  347.         When you try to load previously saved tags, PowerVisor will check
  348.         if the structure exists and will use this pointer instead of
  349.         the old one. If the structure does not exist, PowerVisor will
  350.         change the type of the tag to Long/Ascii and give a warning
  351.         at the end of the loading
  352.       - Behaviour changed : 'LoadTags' no longer clears the current tag
  353.         list but adds the tags from the file to the current tag list
  354.       - Note that the PVSD file format has changed (used for 'LoadTags'
  355.         and 'SaveTags'). PowerVisor does NOT understand the format
  356.         used by PowerVisor V1.00 and V1.01
  357.       - Install script is better. We check if the files exist before
  358.         we try to copy them. If a file doesn't exist we ask another
  359.         pathname to the user. This means that you can distribute
  360.         PowerVisor on different disks (in fact you will have to
  361.         distribute PowerVisor on different disks if you don't compress
  362.         the files). The installation script won't give errors because
  363.         of non existant files. Simply put the other disk in the drive
  364.       - We print more information in the cli structure (with the 'info'
  365.         command)
  366.       - New glossary file for explaining some specific PowerVisor
  367.         terminology
  368.       - 'Why' command is gone. It is more efficient to define an
  369.         alias for 'why' in s/PowerVisor-startup
  370.       - Some optimizations, PowerVisor is a bit shorter. This has
  371.         some effect on some internal fields. See the
  372.         'TheWizardCorner' file for more info about the format of
  373.         the commands in the routine table
  374.       - Because of the previous optimization there are no more commands
  375.         working in ARexx but not in PowerVisor and vice versa. You can
  376.         now use the 'front', 'hide', 'sync', ... commands in PowerVisor
  377.         too. And the 'clip' and 'remclip' commands work in ARexx
  378.       - Some new 'pvcall' functions for logical windows
  379.       - Bug solved in 'salias' alias. This alias loosed memory everytime
  380.         we runned it
  381.       - The 'co' function (or 'GetCode' ML-script) will not crash anymore
  382.         if used in AmigaDOS 1.3 with a non special key. The function will
  383.         return 0 instead
  384.       - A complete new directory 'PVDevelop' for the PowerVisor Wizards.
  385.         This subdirectory contains include files and libraries useful
  386.         to make ML-scripts in C or machinelanguage
  387.       - New assign : 'pv' to the root of the PowerVisor subdirectory.
  388.         This assign is only used by the develop files
  389.       - 'openlw', 'openpw', 'xwin', 'rwin', 'owin', 'awin' and 'dwin'
  390.         give an error when there is not enough memory. In the previous
  391.         version, the memory failure was simply ignored
  392.       - No more ugly flickering of the BUSY prompt when executing
  393.         ARexx scripts
  394.       - Bug solved in 'unasm' with very long instructions. The hexadecimal
  395.         words would overwrite the instruction
  396.       - New 'bin' alias in s/PowerVisor-startup to show the binary
  397.         representation of a number
  398.       - New 'asm' alias and s:pv/assem.pv ARexx program for a simple
  399.         assembler. See s:pv/assem.pv for more info about the assembler
  400.       - Two new 'pvcall' functions to disassemble one line of memory
  401.         in a string (s:pv/assem.pv uses this)
  402.       - The PowerVisor expression evaluator is more strict. You
  403.         MUST always close all brackets. I have done this because there were
  404.         some problems (especially in 'alias') if badly formed expressions
  405.         are used
  406.       - The same is true for the group operator
  407.       - New 'cmd' alias and ARexx script to execute Cli commands from
  408.         within PowerVisor
  409.       - Bug solved in strong quote parsing
  410.       - PowerVisor commands called from ARexx are not interruptable anymore
  411.         with <esc>
  412.       - Important change in the logical window system. Input is now local
  413.         to a logical window. This means that when a command waits for
  414.         input (either a line of input or a key (-MORE- for example)) all
  415.         other logical windows will be locked. This means that accidently
  416.         hitting a key will not have undesirable results. All input is
  417.         redirected to the active logical window (the one with the full
  418.         (blue) titlebar)
  419.       - <esc> and <ralt>-<help only work for the output appearing on the
  420.         'ACTIVE' logical window, so you have to use <tab> to interrupt a
  421.         command running on another logical window (also see the previous
  422.         item)
  423.       - Note that the stringgadget still behaves weird in AmigaDOS 1.3
  424.         If anyone out there knows a legal way to UNSELECT (UnActivate)
  425.         a stringgadget I would appreciate it very much. In AmigaDOS 2.0
  426.         simply removing the gadget and adding it again is enough to
  427.         unselect the gadget, but this does not seem true in AmigaDOS 1.3.
  428.       - New 'event' command to add an input event to the main handler.
  429.         This is useful for macros (key attachements)
  430.       - The AmigaDOS 1.2/1.3 version of PowerVisor doesn't need arp.library
  431.         anymore (I needed it only for the 32 bit multiply and divide. I
  432.         have now put these two routines in pv13)
  433.       - Fixed yet another bug in the structure viewing and the 'info'
  434.         command. If the list item in a structure was a string, there would
  435.         be some strange characters after the string
  436.       - Many bugs and errors are corrected in the online help and tutor
  437.         files
  438.       - AT LAST ! Mstruct is converted to AmigaDOS 1.2/1.3 ! Now you can
  439.         make your own structures and use them in PowerVisor even if you
  440.         don't use AmigaDOS 2.0
  441.       - Major change in the history buffer mechanics. The history buffer
  442.         now works like in the AmigaDOS 2.0 shell. It is no longer a
  443.         circular list (how coud I ever have such a bad idea :-)
  444.         This means of course that s:pv/PrintHist.pv, s:pv/SearchHist
  445.         and Source/SearchHist.asm have changed a bit. I hope you had not
  446.         written anything using the internal structure of the history
  447.         buffer, because you will have to change your programs if you did
  448.       - At last ! The autorepeat bug in the AmigaDOS 1.2/1.3 version of
  449.         PowerVisor is solved. You can now scroll in the history buffer and
  450.         in the logical windows with autorepeat
  451.       - Although it was already possible to set a font for a logical window,
  452.         this could not be done automatically and the stringgadget and
  453.         logical window size bars remained in topaz 8. Now it is possible to
  454.         set the default font for PowerVisor (with 'prefs font'). This font
  455.         is used for all new logical windows (you can of course still change
  456.         this font when the logical window is already open), for the
  457.         stringgadget, for the logical window size bars and for the screen.
  458.       - WARNING !!! The File format of s:PowerVisor-config has changed !
  459.         Please delete this file first before you start the new version of
  460.         PowerVisor !!!
  461.       - Commandline options for PowerVisor are removed since they were
  462.         not very useful
  463.       - All the 'prefs' commands have a more readable output. I use decimal
  464.         output when decimal is more appropriate than hexadecimal
  465.       - Some pvcall functions are removed because they were obsolete (Signal
  466.         command and IDCMP command)
  467.       - MAJOR ! The AmigaDOS 2.0 version of PowerVisor finally supports
  468.         menus. You can make your own menus with your favorite commands in
  469.         it. I'm very sorry, but this is only for the AmigaDOS 2.0 version
  470.       - When 'reqtools.library' (© Nico François) is available, PowerVisor
  471.         will use this library for requesters with the new commands :
  472.             'reqload', 'reqsave', 'request' and 'getstring'
  473.         Otherwise, simple PowerVisor constructions are automatically used :
  474.             'scan', 'key()'
  475.       - There is a new predefined constant 'input'. This constant contains
  476.         the pointer to the last input string (with 'scan', 'getstring',
  477.         'reqload' and 'reqsave'). You don't have to worry anymore about
  478.         freeing all the strings allocated with 'scan'
  479.       - Bug fix in 'debug l' and 'debug n'. We did loose some memory when
  480.         the loading failed or when 'debug n' was interrupted by the user
  481.       - More predefined pens (24 instead of 16), 19 of these pens are used
  482.       - Four new pens for the colours of the stringgadget (only AmigaDOS 2.0)
  483.       - Bug fixed in 'symbol' command. PowerVisor sometimes said there were
  484.         no symbols even if it previously loaded them. This bug was harmless
  485.         but I fixed it anyway :-)
  486.  
  487.  
  488. All files
  489. ---------
  490.  
  491.      PowerVisorLib (dir)      This subdirectory contains files needed
  492.                               to use to powervisor.library in your programs
  493.  
  494.        pv_lib.fd              fd-file containing function definitions for
  495.                               the powervisor.library functions
  496.        pv_lib.h               C header file containing pragmas for the
  497.                               powervisor.library functions. This file
  498.                               is written for Lattice C 5.0. If you use
  499.                               another compiler (like Aztec) you may
  500.                               need to rewrite this file. If you use a
  501.                               C compiler with no support for pragmas you
  502.                               must make stubs to call the library functions
  503.        pv_lib.i               Machinelanguage header file.
  504.  
  505.      c (dir)                  This subdirectory contains all executable
  506.                               files. All files ending with '13' are for
  507.                               AmigaDOS 1.3.
  508.  
  509.        ArcFiles               The QuickHelp utilities for AmigaDOS 2.0
  510.        Help                   Read docs/help.doc for more info
  511.        MakeHelp
  512.  
  513.        ArcFiles13             The QuickHelp utilities for AmigaDOS 1.3
  514.        Help13                 Read docs/help13.doc for more info
  515.        MakeHelp13
  516.  
  517.        MStruct                Program to convert pseudo include files to pvsd
  518.                               files.
  519.                               This program will be enhanced in future
  520.                               to support full include files.
  521.        MStruct13              AmigaDOS 1.3 version of MStruct
  522.        pv                     AmigaDOS 2.0 version of PowerVisor
  523.        pv13                   AmigaDOS 1.3 version of PowerVisor
  524.        Input                  Little program needed for the installation
  525.                               script. 'Input' prints the first argument
  526.                               on the screen and waits for input. The input
  527.                               is put in the specified file (second argument).
  528.                               Syntax : Input <prompt line> <file name>
  529.        DevName                Little program needed for the installation
  530.                               script. 'DevName' reads the first line from
  531.                               a file and replaces the same file with another
  532.                               file containing only this first line altered
  533.                               in the following way :
  534.                                  if the first line ends with a ':' nothing
  535.                                  happens
  536.                                  If the first line ends with a '/' nothing
  537.                                  happens
  538.                                  Otherwise a '/' is appended to the first
  539.                                  line
  540.                               Syntax : DevName <file name>
  541.        DirName                Little program needed for the installation
  542.                               script.  'DirName' is equivalent to 'DevName'.
  543.                               'DirName' removes the last character of the
  544.                               first line if it is a '/'.
  545.                               Syntax : DirName <file name>
  546.  
  547.      libs (dir)               All libraries needed by PowerVisor
  548.  
  549.        powervisor.library     This library is needed by PowerVisor
  550.  
  551.      docs (dir)               All documents for PowerVisor
  552.  
  553.        GettingStarted         Read this file if you are a first-time user
  554.        Aliases                This file explains everything about the
  555.                               aliases defined in s/PowerVisor-startup
  556.                               and s/pv/ExtraAliases
  557.        Expressions            All about expression evaluation in PowerVisor
  558.        Screen                 Everything about screens and windows
  559.        InstallingPowerVisor   How to install PowerVisor
  560.        Scripts                Everything about scripts (ARexx, ...)
  561.        LookingAtThings        How to look at memory, disassemble, ...
  562.        Debug                  How to debug programs
  563.  
  564.        CommandReference       All PowerVisor commands explained
  565.        Functions              All PowerVisor functions explained
  566.        Lists                  All lists
  567.  
  568.        Glossary               The PowerVisor glossary, reading this file is
  569.                               a very good way to learn all (or most)
  570.                               PowerVisor terminology
  571.  
  572.        TechnicalInfo          Some technical information
  573.        TheWizardCorner        Only for VERY experienced users. Using this
  574.                               file you can customize PowerVisor to enormous
  575.                               degrees. Look in the 'Source' directory for
  576.                               examples using information from this file.
  577.                               Also look at the 'PVDevelop' directory useful
  578.                               for making your own powerful scripts (and
  579.                               ML-scripts)
  580.  
  581.        Global.index           The index for all above files
  582.  
  583.        GettingStarted.idx     The individual index files for all tutor
  584.        Expressions.idx        and reference files
  585.        Screen.idx
  586.        Aliases.idx
  587.        InstallingPowerVisor.idx
  588.        Scripts.idx
  589.        LookingAtThings.idx
  590.        Debug.idx
  591.        CommandReference.idx
  592.        Functions.idx
  593.        Lists.idx
  594.        TechnicalInfo.idx
  595.        TheWizardCorner.idx
  596.  
  597.        Screen.contents        The contents files for all tutor files
  598.        GettingStarted.contents
  599.        Aliases.contents
  600.        Expressions.contents
  601.        InstallingPowerVisor.contents
  602.        Scripts.contents
  603.        LookingAtThings.contents
  604.        Debug.contents
  605.        CommandReference.contents
  606.        Functions.contents
  607.        Lists.contents
  608.        TechnicalInfo.contents
  609.        TheWizardCorner.contents
  610.  
  611.        Help.doc               Manual for QuickHelp
  612.        Help13.doc             Manual for QuickHelp 1.3
  613.  
  614.        CancelDouble           This program cancels all double lines in
  615.                               a file. This program is used by
  616.                               'MakeGlobalIndex'
  617.        CancelDouble.c         The source for 'CancelDouble'. You should
  618.                               be able to compile this program on any
  619.                               C-compiler
  620.        ExtractIndex.rexx      This rexx script is used by 'MakeIndex' to
  621.                               construct the index file for one individual
  622.                               tutor file
  623.        ExtractIndexSE.rexx    This rexx script is used by 'MakeIndex.se' to
  624.                               construct the index file for one individual
  625.                               tutor file
  626.        MakeGlobalIndex        This script file combines all index files
  627.                               made by 'MakeIndex' to make the global index
  628.        MakeIndex              Make the index and contents file for one
  629.                               tutorial file.
  630.                               This version uses the 'egrep' (or 'gnugrep')
  631.                               command by 'Free Software Foundation, Inc.'
  632.                               This version is faster than 'MakeIndex.se'
  633.                               but you need 'egrep' of course ('egrep'
  634.                               is not distributed with PowerVisor)
  635.        MakeIndex.se           Make the index and contents file for one
  636.                               tutorial file. This version uses the
  637.                               standard AmigaDOS 'search' command, but it
  638.                               is slower
  639.  
  640.      Source (dir)             This subdirectory contains sources for
  641.                               various scripts and example programs
  642.                               included with PowerVisor
  643.  
  644.        FreeError.asm          These two programs crash your Amiga,
  645.        stackovf.asm           except when PowerVisor is running (I hope)
  646.                               Executables for these files are in the
  647.                               'Examples' subdirectory
  648.  
  649.        BuggyProgram.asm       Example programs used in the 'debug' tutorial
  650.        BuggyProgram2.asm      file. Executables for these files are in the
  651.                               'Examples' subdirectory
  652.  
  653.        CheckBrackets.c        Program to check brackets. Executable file
  654.                               is in 's/pv'. Source is for Lattice C 5.0
  655.                               only
  656.        GetCode.c              Program to compute the keycode for a named
  657.                               key. Executable file is in 's/pv'. Source is
  658.                               for Lattice C 5.0 only
  659.        GetQual.c              Program to compute the keyqualifier for a
  660.                               named qualifier. Executable file is in 's/pv'.
  661.                               Source is for Lattice C 5.0 only
  662.  
  663.        Exec.struct            PowerVisor source for 'Exec' structure
  664.                               definitions.
  665.                               pvsd file is in 's/pv'
  666.        intuition.struct       PowerVisor source for 'Intuition' window
  667.                               structure definition.
  668.                               pvsd file is in 's/pv'
  669.  
  670.        mkeys.explained        Same script file as 's/pv/mkeys' but with
  671.                               a lot of comments
  672.  
  673.        pptest.asm             Program to test the powervisor.library.
  674.                               Use as an example. Executable file is in
  675.                               the 'Examples' subdirectory
  676.        takeme.asm             Program to test 'debug t'
  677.                               Executable file is in the 'Examples'
  678.                               subdirectory
  679.        SearchHist.asm         Source for history search program. Executable
  680.                               file is in 's/pv'
  681.  
  682.  
  683.      PVDevelop (dir)          This subdirectory contains include files and
  684.                               libraries useful for PowerVisor Wizards. There
  685.                               are include files for C and machinelanguage
  686.  
  687.        include (dir)          Subdirectory containing all include files
  688.                               for PowerVisor (except for the
  689.                               powervisor.library include files because these
  690.                               are in another subdirectory)
  691.  
  692.           PV (dir)            The recomended place for the include files
  693.  
  694.             ARexxBase.h       The ARexx Base structures
  695.             ARexxBase.i
  696.             DebugBase.h       The Debug Base structures
  697.             DebugBase.i
  698.             EvalBase.h        The Eval Base structures
  699.             EvalBase.i
  700.             FileBase.h        The File Base structures
  701.             FileBase.i
  702.             GeneralBase.h     The General Base structures
  703.             GeneralBase.i
  704.             ListBase.h        The List Base structures
  705.             ListBase.i
  706.             MainBase.h        The Main Base structures
  707.             MainBase.i
  708.             MemoryBase.h      The Memory Base structures
  709.             MemoryBase.i
  710.             ScreenBase.h      The Screen Base structures
  711.             ScreenBase.i
  712.             PVCallRoutines.h  Protos for the PVCall routines
  713.             PVCallTable.h     Table with PVCall routine numbers
  714.             PVCallTable.i
  715.             PVMemory.h        PowerVisor memory allocation structures
  716.             PVMemory.i
  717.  
  718.           Lib (dir)           All the C libraries (for SAS/C) to make
  719.                               calling PVCall functions from C easier
  720.  
  721.             PVCallStub.lib    The library for small code
  722.             PVCallStubNB.lib  The library for large code
  723.  
  724.             Source (dir)      The source for these libraries
  725.  
  726.               README          A README explaining some things. If you
  727.                               'execute' this file, the two libraries
  728.                               will be build again
  729.  
  730.               PVCallStub.i    Include file needed for all functions
  731.  
  732.               makefile        makefile used by 'README'
  733.  
  734.               PVCBeep.asm     All sources for all PVCall functions
  735.               PVCError.asm
  736.               PVCAddAutoClear.asm
  737.               PVCAddGlobalAutoClear.asm
  738.               PVCAddStringToHist.asm
  739.               PVCAdvanceHistory.asm
  740.               PVCAllocPVBlock.asm
  741.               PVCAppendString.asm
  742.               PVCCallMLScript.asm
  743.               PVCClosePVHandle.asm
  744.               PVCCompareStrings.asm
  745.               PVCComputeGadgetSignal.asm
  746.               PVCConvertAlias.asm
  747.               PVCCopyString.asm
  748.               PVCCreateConstant.asm
  749.               PVCCreateFunction.asm
  750.               PVCErrorHandler.asm
  751.               PVCEvaluate.asm
  752.               PVCFreePVBlock.asm
  753.               PVCGetARexxBase.asm
  754.               PVCGetDebugBase.asm
  755.               PVCGetEvalBase.asm
  756.               PVCGetExecLevel.asm
  757.               PVCGetFileBase.asm
  758.               PVCGetGeneralBase.asm
  759.               PVCGetHistoryLine.asm
  760.               PVCGetListBase.asm
  761.               PVCGetMainBase.asm
  762.               PVCGetMemoryBase.asm
  763.               PVCGetModeRoutines.asm
  764.               PVCGetRexxList.asm
  765.               PVCGetRoutines.asm
  766.               PVCGetScreenBase.asm
  767.               PVCGetSnapBuffer.asm
  768.               PVCGetStringGadget.asm
  769.               PVCGetStringGBuf.asm
  770.               PVCGetStringInfo.asm
  771.               PVCGetVarAddress.asm
  772.               PVCInstallPostCmd.asm
  773.               PVCInstallPreCmd.asm
  774.               PVCInstallQuitCmd.asm
  775.               PVCInstallSnapCmd.asm
  776.               PVCLowerHistory.asm
  777.               PVCParseString.asm
  778.               PVCPrint.asm
  779.               PVCPrintNum.asm
  780.               PVCReAllocPVMemoryBlock.asm
  781.               PVCReAllocPVQuickBlock.asm
  782.               PVCRefreshLogWin.asm
  783.               PVCRefreshStringG.asm
  784.               PVCRemoveGlobalAutoClear.asm
  785.               PVCRemVar.asm
  786.               PVCSetCursorPos.asm
  787.               PVCSetDebugMode.asm
  788.               PVCSkipSpaces.asm
  789.               PVCSnapWord.asm
  790.               PVCDisassemble.asm
  791.               PVCCmdDisassemble.asm
  792.               PVCPutChar.asm
  793.  
  794.      s (dir)                  Online help and scripts
  795.  
  796.        PowerVisor-menus       Only for the AmigaDOS 2.0 version. This
  797.                               file contains the description of the menus
  798.                               used in PowerVisor. The format is not
  799.                               difficult. You can change this file if
  800.                               you'd like other menus
  801.        PowerVisor-help        Online help file. This file contains all
  802.                               online help and the templates. You can't
  803.                               use 'help' and 'why' when this file is
  804.                               not present. Note that the online help
  805.                               file is not the good place to start learning
  806.                               PowerVisor. Use the tutorial files in the
  807.                               'docs' subdirectory for that purpose.
  808.        PowerVisor-ctrl        Online help control file. Use the QuickHelp
  809.                               utilities to update this file when you
  810.                               have changed something in the PowerVisor-help
  811.                               file. You need this file if you want
  812.                               online help
  813.        PowerVisor-errors      All error messages for PowerVisor. You need
  814.                               this file if you want to make errors :-)
  815.                               No, you need this file if you want to see
  816.                               a sensible error message.
  817.                               Each line in this file must be 70 bytes
  818.        PowerVisor-startup     The startup script for PowerVisor. This
  819.                               script installs various new commands and
  820.                               keys
  821.  
  822.           pv (dir)            This subdirectory contains all scripts you
  823.                               can use
  824.  
  825.             db                PowerVisor script to install the fullscreen
  826.                               debugger. This script also assigns some
  827.                               keys to useful debugging commands
  828.             ExampleSetting    PowerVisor script to show an other window
  829.                               configuration posibility. Use as an example
  830.                               for more useful settings
  831.             ExtraAliases      This file contains some extra useful
  832.                               aliases not defined in the s/PowerVisor-startup
  833.                               file
  834.             icopy             PowerVisor script to install a logical window
  835.                               copy feature. Press 'Shift-PrtSc' to store
  836.                               the active logical window in an internal
  837.                               buffer. Press 'PrtSc' to retrieve this buffer
  838.                               into another active logical window.
  839.                               This script uses 'GetLogWin' and 'CopyLogWin'
  840.             CheckBrackets     ML script to check for brackets in the
  841.                               commandline. Source is in the 'Source'
  842.                               subdirectory. See the 's/Powervisor-startup'
  843.                               file for an example of how to install this
  844.                               feature
  845.             GetCode           ML script to compute the code of a named
  846.                               key. Source is in the 'Source' subdirectory.
  847.                               Note that if you have AmigaDOS 1.3 you can
  848.                               only use this script to compute the code
  849.                               of special keys (like 'enter' and 'esc')
  850.                               and not of normal keys (like 'a', '3', ...).
  851.                               This script is installed as a function in the
  852.                               's/PowerVisor-startup' file
  853.             CopyLogWin        ML script to copy the active logical window
  854.                               to a buffer. This script is used by 'icopy'.
  855.                               Source is in the 'Source' directory
  856.             GetLogWin         ML script to copy a buffer to the active
  857.                               logical window. This script is used by 'icopy'.
  858.                               Source is in the 'Source' directory
  859.             GetQual           ML script to compute the qualifier of a named
  860.                               qualifier. Source is in the 'Source'
  861.                               subdirectory. This script is installed as a
  862.                               function in the 's/PowerVisor-startup' file
  863.             SearchHist        ML script to search in the history buffer.
  864.                               Source is in the 'Source' subdirectory. This
  865.                               script is installed on a key in the
  866.                               's/PowerVisor-startup' file
  867.             ikey              This PowerVisor script installs various
  868.                               special features
  869.             mkeys             PowerVisor script for a memory display
  870.                               utility
  871.             PrintHist.pv      ARexx script to print the contents of the
  872.                               current history buffer
  873.             PrintMode.pv      ARexx script to print the current mode
  874.                               setting in a readable format
  875.             ShowAscii.pv      ARexx script to show all ascii chars on the
  876.                               PowerVisor window
  877.             Assem.pv          Little ARexx assembler. Use the 'asm' alias
  878.                               defined in s:PowerVisor-startup to call this
  879.                               script. See the script for more info about
  880.                               the script
  881.             intuition.pvsd    pvsd file for the Window structure.
  882.                               Source is in the 'Source' subdirectory
  883.             Exec.pvsd         pvsd file for all Exec structures
  884.                               Source is in the 'Source' subdirectory
  885.  
  886.      Examples (dir)           This subdirectory contains some example
  887.                               programs. Sources for most of these programs
  888.                               can be found in the 'Source' subdirectory
  889.  
  890.        BuggyProgram           Programs used in the 'Debug' tutor file
  891.        BuggyProgram2
  892.  
  893.        crash3                 Some crash programs
  894.        crash4
  895.        crash5
  896.        crash8
  897.        crasha
  898.        freeerror
  899.        stackovf
  900.  
  901.        pptest                 powervisor.library test program
  902.        takeme                 'debug t' test program
  903.  
  904.   ReadThisFirst               This file
  905.   pv.bugs                     All bugs in the current version of Powervisor
  906.   Install                     Execute this file to install PowerVisor
  907.                               or click on icon from WorkBench
  908.   Install.script              Install script used by 'Install' (Don't
  909.                               execute this)
  910.  
  911.  
  912. Environment
  913. -----------
  914.  
  915.    PowerVisor normally does not expect special assignments or such.
  916.    s/PowerVisor-startup however does expect 'fd' to be assigned to
  917.    the subdirectory containing fd-files (at least exec_lib.fd,
  918.    dos_lib.fd, graphics_lib.fd and intuition_lib.fd). If you do not
  919.    have these fd-files (note that you can find them on the AmigaDOS
  920.    1.3 Extras disk) you must remove four lines in s/PowerVisor-startup
  921.    starting with '-lfd'. You will not be able to use the library
  922.    functions defined in the fd-files if you do this (Note that
  923.    PowerVisor makes very good use of these fd-files, so I recommend
  924.    that you install them if you have a harddisk).
  925.  
  926.    s/PowerVisor-startup also expects the following files in the
  927.    s:pv directory : db, CheckBrackets, GetCode, GetQual and SearchHist.
  928.  
  929.    You can of course adapt s:PowerVisor-startup to your own wishes.
  930.  
  931.  
  932.    If you have reqtools.library (by Nico François) PowerVisor will use
  933.    it for requesters. In the next distribution of PowerVisor, reqtools
  934.    will be included with all the other files.
  935.  
  936.  
  937.    If you use AmigaDOS 1.2 or 1.3 I recommend that you use
  938.    'FastFonts' (FF) by C.Heath. This program greatly speeds up the
  939.    PowerVisor display. This is not necessary in AmigaDOS 2.0 since
  940.    Commodore did a good optimizing job.
  941.  
  942.    If you use AmigaDOS 1.2, 1.3 or 2.0 and you have a fast processor
  943.    (68020 or higher) I recommend that you use 'CpuBlit' by Eddy Carroll.
  944.    This program gives an even greater speed increase.
  945.  
  946.  
  947. Installation
  948. ------------
  949.  
  950.    Installing PowerVisor should be easy. Simply execute 'Install' (with
  951.    the current directory set to the root directory of the PowerVisor
  952.    distribution) or double click on the icon.
  953.    You will get an interactive install session.
  954.  
  955.    Note that the installation script has only been tested in WorkBench 2.0.
  956.    I hope it works with WorkBench 1.3. The installation script does NOT
  957.    work with WorkBench 1.2. I tried to make the script as simple as
  958.    possible but I failed :-)
  959.  
  960.    Note that the script needs the following cli commands :
  961.       - setenv       (builtin command in AmigaDOS 2.0)
  962.       - if           (builtin command in AmigaDOS 2.0)
  963.       - else         (builtin command in AmigaDOS 2.0)
  964.       - endif        (builtin command in AmigaDOS 2.0)
  965.       - skip         (builtin command in AmigaDOS 2.0)
  966.       - lab          (builtin command in AmigaDOS 2.0)
  967.       - ask          (builtin command in AmigaDOS 2.0)
  968.       - echo         (builtin command in AmigaDOS 2.0)
  969.       - endcli       (builtin command in AmigaDOS 2.0)
  970.       - makedir
  971.       - copy
  972.       - version
  973.       - delete
  974.       - dir
  975.       - input        (included in the PowerVisor distribution)
  976.       - devname      (included in the PowerVisor distribution)
  977.       - dirname      (included in the PowerVisor distribution)
  978.  
  979.  
  980. Tutor files
  981. -----------
  982.  
  983. Here are all the files in the prefered order to read them
  984.  
  985. tutor files :
  986.  
  987.    GettingStarted             For the first time user
  988.    Expressions                Very important to read
  989.    Screen
  990.    InstallingPowerVisor
  991.    LookingAtThings
  992.    Debug
  993.    Scripts
  994.  
  995. reference files :
  996.  
  997.    CommandReference           Very useful file
  998.    Functions
  999.    Aliases
  1000.    Lists
  1001.    TechnicalInfo
  1002.  
  1003. if you want to look up a specific word :
  1004.  
  1005.    Glossary
  1006.  
  1007. for very experienced users :
  1008.  
  1009.    TheWizardCorner            Only read if you are a PowerVisor wizard !!!!!
  1010.  
  1011.  
  1012.  
  1013. Authors
  1014. -------
  1015.  
  1016.    André Pelckmans for the disassembler
  1017.    Jorrit Tyberghein for the rest
  1018.  
  1019.  
  1020. Address
  1021. -------
  1022.  
  1023.    Jorrit Tyberghein
  1024.    Hepmansbossen 31
  1025.    2450 Meerhout BELGIUM
  1026.  
  1027.  
  1028. Thanks to
  1029. ---------
  1030.  
  1031.    André Pelckmans for his disassembler and for giving me all
  1032.    the programming help I need.
  1033.    Without him I wouldn't have a computer in the first place (I think).
  1034.  
  1035.    Nico François for his debugging, his numerous remarks and suggestions.
  1036.    Without him PowerVisor would have looked COMPLETELY different :-)
  1037.    (and without him I would have to use two disks to backup the source
  1038.    of PowerVisor)
  1039.  
  1040.    Nico François for his WONDERFUL reqtools.library. If you want to use
  1041.    well designed, flexible and powerful requesters there is no better choice
  1042.  
  1043.    Ives Aerts for his useful suggestions and criticism.
  1044.  
  1045.    Adam Hill, Christian Weber, Steven Reiz and Dominic Giampaolo
  1046.    for their bug reports and suggestions.
  1047.  
  1048.    Some extra thanks to Adam Hill for his efforts to arouse
  1049.    interrest in PowerVisor (in BIX for example).
  1050.  
  1051.    The software people at Commodore for their VERY USEFUL debugging
  1052.    tools (like 'Enforcer', 'MungWall', ...).
  1053.    And also for their presence on usenet.
  1054.  
  1055.    To my parents of course.
  1056.  
  1057.    Also thanks to the Amiga computer for being an Amiga.
  1058.  
  1059.                __
  1060.               ///
  1061.              ///
  1062.             ///
  1063.    __      ///
  1064.    \\\    ///       Amiga, the computer for the creative mind
  1065.     \\\  ///
  1066.      \\\///
  1067.       \XX/
  1068.  
  1069.  
  1070.